<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html 
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Class: WillPaginate::Collection</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  <meta http-equiv="Content-Script-Type" content="text/javascript" />
  <link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
  <script type="text/javascript">
  // <![CDATA[

  function popupCode( url ) {
    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
  }

  function toggleCode( id ) {
    if ( document.getElementById )
      elem = document.getElementById( id );
    else if ( document.all )
      elem = eval( "document.all." + id );
    else
      return false;

    elemStyle = elem.style;
    
    if ( elemStyle.display != "block" ) {
      elemStyle.display = "block"
    } else {
      elemStyle.display = "none"
    }

    return true;
  }
  
  // Make codeblocks hidden by default
  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
  
  // ]]>
  </script>

</head>
<body>



    <div id="classHeader">
        <table class="header-table">
        <tr class="top-aligned-row">
          <td><strong>Class</strong></td>
          <td class="class-name-in-header">WillPaginate::Collection</td>
        </tr>
        <tr class="top-aligned-row">
            <td><strong>In:</strong></td>
            <td>
                <a href="../../files/vendor/plugins/will_paginate/lib/will_paginate/collection_rb.html">
                vendor/plugins/will_paginate/lib/will_paginate/collection.rb
                </a>
        <br />
            </td>
        </tr>

        <tr class="top-aligned-row">
            <td><strong>Parent:</strong></td>
            <td>
                Array
            </td>
        </tr>
        </table>
    </div>
  <!-- banner header -->

  <div id="bodyContent">



  <div id="contextContent">

    <div id="description">
      <h1>The key to pagination</h1>
<p>
Arrays returned from paginating finds are, in fact, instances of this
little class. You may think of <a
href="Collection.html">WillPaginate::Collection</a> as an ordinary array
with some extra properties. Those properties are used by view helpers to
generate correct page links.
</p>
<p>
<a href="Collection.html">WillPaginate::Collection</a> also assists in
rolling out your own pagination solutions: see <tt><a
href="Collection.html#M000043">create</a></tt>.
</p>
<p>
If you are writing a library that provides a collection which you would
like to conform to this API, you don&#8216;t have to copy these methods
over; simply make your plugin/gem dependant on the
&quot;mislav-will_paginate&quot; gem:
</p>
<pre>
  gem 'mislav-will_paginate'
  require 'will_paginate/collection'

  # WillPaginate::Collection is now available for use
</pre>

    </div>


   </div>

    <div id="method-list">
      <h3 class="section-bar">Methods</h3>

      <div class="name-list">
      <a href="#M000043">create</a>&nbsp;&nbsp;
      <a href="#M000042">new</a>&nbsp;&nbsp;
      <a href="#M000047">next_page</a>&nbsp;&nbsp;
      <a href="#M000045">offset</a>&nbsp;&nbsp;
      <a href="#M000044">out_of_bounds?</a>&nbsp;&nbsp;
      <a href="#M000046">previous_page</a>&nbsp;&nbsp;
      <a href="#M000049">replace</a>&nbsp;&nbsp;
      <a href="#M000048">total_entries=</a>&nbsp;&nbsp;
      </div>
    </div>

  </div>


    <!-- if includes -->

    <div id="section">





    <div id="attribute-list">
      <h3 class="section-bar">Attributes</h3>

      <div class="name-list">
        <table>
        <tr class="top-aligned-row context-row">
          <td class="context-item-name">current_page</td>
          <td class="context-item-value">&nbsp;[R]&nbsp;</td>
          <td class="context-item-desc"></td>
        </tr>
        <tr class="top-aligned-row context-row">
          <td class="context-item-name">per_page</td>
          <td class="context-item-value">&nbsp;[R]&nbsp;</td>
          <td class="context-item-desc"></td>
        </tr>
        <tr class="top-aligned-row context-row">
          <td class="context-item-name">total_entries</td>
          <td class="context-item-value">&nbsp;[R]&nbsp;</td>
          <td class="context-item-desc"></td>
        </tr>
        <tr class="top-aligned-row context-row">
          <td class="context-item-name">total_pages</td>
          <td class="context-item-value">&nbsp;[R]&nbsp;</td>
          <td class="context-item-desc"></td>
        </tr>
        </table>
      </div>
    </div>
      


    <!-- if method_list -->
    <div id="methods">
      <h3 class="section-bar">Public Class methods</h3>

      <div id="method-M000043" class="method-detail">
        <a name="M000043"></a>

        <div class="method-heading">
          <a href="#M000043" class="method-signature">
          <span class="method-name">create</span><span class="method-args">(page, per_page, total = nil) {|pager| ...}</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Just like <tt><a href="Collection.html#M000042">new</a></tt>, but yields
the object after instantiation and returns it afterwards. This is very
useful for manual pagination:
</p>
<pre>
  @entries = WillPaginate::Collection.create(1, 10) do |pager|
    result = Post.find(:all, :limit =&gt; pager.per_page, :offset =&gt; pager.offset)
    # inject the result array into the paginated collection:
    pager.replace(result)

    unless pager.total_entries
      # the pager didn't manage to guess the total count, do it manually
      pager.total_entries = Post.count
    end
  end
</pre>
<p>
The possibilities with this are endless. For another example, here is how
<a href="../WillPaginate.html">WillPaginate</a> used to define pagination
for Array instances:
</p>
<pre>
  Array.class_eval do
    def paginate(page = 1, per_page = 15)
      WillPaginate::Collection.create(page, per_page, size) do |pager|
        pager.replace self[pager.offset, pager.per_page].to_a
      end
    end
  end
</pre>
<p>
The Array#paginate API has since then changed, but this still serves as a
fine example of <a href="Collection.html">WillPaginate::Collection</a>
usage.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000043-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000043-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/plugins/will_paginate/lib/will_paginate/collection.rb, line 85</span>
85:     <span class="ruby-keyword kw">def</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">create</span>(<span class="ruby-identifier">page</span>, <span class="ruby-identifier">per_page</span>, <span class="ruby-identifier">total</span> = <span class="ruby-keyword kw">nil</span>)
86:       <span class="ruby-identifier">pager</span> = <span class="ruby-identifier">new</span>(<span class="ruby-identifier">page</span>, <span class="ruby-identifier">per_page</span>, <span class="ruby-identifier">total</span>)
87:       <span class="ruby-keyword kw">yield</span> <span class="ruby-identifier">pager</span>
88:       <span class="ruby-identifier">pager</span>
89:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000042" class="method-detail">
        <a name="M000042"></a>

        <div class="method-heading">
          <a href="#M000042" class="method-signature">
          <span class="method-name">new</span><span class="method-args">(page, per_page, total = nil)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Arguments to the constructor are the current page number, per-page limit
and the total number of entries. The last argument is optional because it
is best to do lazy counting; in other words, count <b>conditionally</b>
after populating the collection using the <tt><a
href="Collection.html#M000049">replace</a></tt> method.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000042-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000042-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/plugins/will_paginate/lib/will_paginate/collection.rb, line 49</span>
49:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">initialize</span>(<span class="ruby-identifier">page</span>, <span class="ruby-identifier">per_page</span>, <span class="ruby-identifier">total</span> = <span class="ruby-keyword kw">nil</span>)
50:       <span class="ruby-ivar">@current_page</span> = <span class="ruby-identifier">page</span>.<span class="ruby-identifier">to_i</span>
51:       <span class="ruby-identifier">raise</span> <span class="ruby-constant">InvalidPage</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">page</span>, <span class="ruby-ivar">@current_page</span>) <span class="ruby-keyword kw">if</span> <span class="ruby-ivar">@current_page</span> <span class="ruby-operator">&lt;</span> <span class="ruby-value">1</span>
52:       <span class="ruby-ivar">@per_page</span> = <span class="ruby-identifier">per_page</span>.<span class="ruby-identifier">to_i</span>
53:       <span class="ruby-identifier">raise</span> <span class="ruby-constant">ArgumentError</span>, <span class="ruby-node">&quot;`per_page` setting cannot be less than 1 (#{@per_page} given)&quot;</span> <span class="ruby-keyword kw">if</span> <span class="ruby-ivar">@per_page</span> <span class="ruby-operator">&lt;</span> <span class="ruby-value">1</span>
54:       
55:       <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">total_entries</span> = <span class="ruby-identifier">total</span> <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">total</span>
56:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <h3 class="section-bar">Public Instance methods</h3>

      <div id="method-M000047" class="method-detail">
        <a name="M000047"></a>

        <div class="method-heading">
          <a href="#M000047" class="method-signature">
          <span class="method-name">next_page</span><span class="method-args">()</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
current_page + 1 or nil if there is no next page
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000047-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000047-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/will_paginate/lib/will_paginate/collection.rb, line 112</span>
112:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">next_page</span>
113:       <span class="ruby-identifier">current_page</span> <span class="ruby-operator">&lt;</span> <span class="ruby-identifier">total_pages</span> <span class="ruby-value">? </span>(<span class="ruby-identifier">current_page</span> <span class="ruby-operator">+</span> <span class="ruby-value">1</span>) <span class="ruby-operator">:</span> <span class="ruby-keyword kw">nil</span>
114:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000045" class="method-detail">
        <a name="M000045"></a>

        <div class="method-heading">
          <a href="#M000045" class="method-signature">
          <span class="method-name">offset</span><span class="method-args">()</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Current <a href="Collection.html#M000045">offset</a> of the paginated
collection. If we&#8216;re on the first page, it is always 0. If
we&#8216;re on the 2nd page and there are 30 entries per page, the <a
href="Collection.html#M000045">offset</a> is 30. This property is useful if
you want to render ordinals side by side with records in the view: simply
start with <a href="Collection.html#M000045">offset</a> + 1.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000045-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000045-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/will_paginate/lib/will_paginate/collection.rb, line 102</span>
102:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">offset</span>
103:       (<span class="ruby-identifier">current_page</span> <span class="ruby-operator">-</span> <span class="ruby-value">1</span>) <span class="ruby-operator">*</span> <span class="ruby-identifier">per_page</span>
104:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000044" class="method-detail">
        <a name="M000044"></a>

        <div class="method-heading">
          <a href="#M000044" class="method-signature">
          <span class="method-name">out_of_bounds?</span><span class="method-args">()</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Helper method that is true when someone tries to fetch a page with a larger
number than the last page. Can be used in combination with flashes and
redirecting.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000044-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000044-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/plugins/will_paginate/lib/will_paginate/collection.rb, line 94</span>
94:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">out_of_bounds?</span>
95:       <span class="ruby-identifier">current_page</span> <span class="ruby-operator">&gt;</span> <span class="ruby-identifier">total_pages</span>
96:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000046" class="method-detail">
        <a name="M000046"></a>

        <div class="method-heading">
          <a href="#M000046" class="method-signature">
          <span class="method-name">previous_page</span><span class="method-args">()</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
current_page - 1 or nil if there is no previous page
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000046-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000046-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/will_paginate/lib/will_paginate/collection.rb, line 107</span>
107:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">previous_page</span>
108:       <span class="ruby-identifier">current_page</span> <span class="ruby-operator">&gt;</span> <span class="ruby-value">1</span> <span class="ruby-operator">?</span> (<span class="ruby-identifier">current_page</span> <span class="ruby-operator">-</span> <span class="ruby-value">1</span>) <span class="ruby-operator">:</span> <span class="ruby-keyword kw">nil</span>
109:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000049" class="method-detail">
        <a name="M000049"></a>

        <div class="method-heading">
          <a href="#M000049" class="method-signature">
          <span class="method-name">replace</span><span class="method-args">(array)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
This is a magic wrapper for the original Array#replace method. It serves
for populating the paginated collection after initialization.
</p>
<p>
Why magic? Because it tries to guess the total number of entries judging by
the size of given array. If it is shorter than <tt>per_page</tt> limit,
then we know we&#8216;re on the last page. This trick is very useful for
avoiding unnecessary hits to the database to do the counting after we
fetched the data for the current page.
</p>
<p>
However, after using <tt><a href="Collection.html#M000049">replace</a></tt>
you should always test the value of <tt>total_entries</tt> and set it to a
proper value if it&#8216;s <tt>nil</tt>. See the example in <tt><a
href="Collection.html#M000043">create</a></tt>.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000049-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000049-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/will_paginate/lib/will_paginate/collection.rb, line 134</span>
134:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">replace</span>(<span class="ruby-identifier">array</span>)
135:       <span class="ruby-identifier">result</span> = <span class="ruby-keyword kw">super</span>
136:       
137:       <span class="ruby-comment cmt"># The collection is shorter then page limit? Rejoice, because</span>
138:       <span class="ruby-comment cmt"># then we know that we are on the last page!</span>
139:       <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">total_entries</span>.<span class="ruby-identifier">nil?</span> <span class="ruby-keyword kw">and</span> <span class="ruby-identifier">length</span> <span class="ruby-operator">&lt;</span> <span class="ruby-identifier">per_page</span> <span class="ruby-keyword kw">and</span> (<span class="ruby-identifier">current_page</span> <span class="ruby-operator">==</span> <span class="ruby-value">1</span> <span class="ruby-keyword kw">or</span> <span class="ruby-identifier">length</span> <span class="ruby-operator">&gt;</span> <span class="ruby-value">0</span>)
140:         <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">total_entries</span> = <span class="ruby-identifier">offset</span> <span class="ruby-operator">+</span> <span class="ruby-identifier">length</span>
141:       <span class="ruby-keyword kw">end</span>
142: 
143:       <span class="ruby-identifier">result</span>
144:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000048" class="method-detail">
        <a name="M000048"></a>

        <div class="method-heading">
          <a href="#M000048" class="method-signature">
          <span class="method-name">total_entries=</span><span class="method-args">(number)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
sets the <tt>total_entries</tt> property and calculates
<tt>total_pages</tt>
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000048-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000048-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/will_paginate/lib/will_paginate/collection.rb, line 117</span>
117:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">total_entries=</span>(<span class="ruby-identifier">number</span>)
118:       <span class="ruby-ivar">@total_entries</span> = <span class="ruby-identifier">number</span>.<span class="ruby-identifier">to_i</span>
119:       <span class="ruby-ivar">@total_pages</span>   = (<span class="ruby-ivar">@total_entries</span> <span class="ruby-operator">/</span> <span class="ruby-identifier">per_page</span>.<span class="ruby-identifier">to_f</span>).<span class="ruby-identifier">ceil</span>
120:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>


    </div>


  </div>


<div id="validator-badges">
  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>

</body>
</html>